Collection of Tools & Utilities

home *** CD-ROM | disk | FTP | other *** search

/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / basic / gapdr.zip / GAPQBDR.TXT < prev

Wrap

Text File | 1989-01-18 | 129KB | 3,037 lines

GAPQBDR Door Interface Module - January 18, 1989 A Professional Development Kit For The Professional Programmer (C) Copyright 1988, 1989 The GAP Development Company ALL RIGHTS RESERVED TABLE OF CONTENTS Page DESCRIPTION 2 GETTING STARTED 3 COMPILING AND LINKING 6 SYSOP SETUP AND FUNCTIONS 8 GLOBAL VARIABLES 11 CONSTANTS 11 ANSI CONSTANTS 11 DOOR.SYS VARIABLES 12 INTEGERS 12 LONGS 12 STRINGS 12 GAPQBDR GLOBALS 13 INTEGERS 13 LONGS 13 STRINGS 13 GAPDOS.DAT VARIABLES 13 USERS.DAT VARIABLES 14 PCBOARD.SYS VARIABLES 15 PCB USERS VARIABLES 15 GLOBAL VARIABLES - ALPHABETICALLY By Type 17 CONSTANTS 17 INTEGERS 17 LONGS 18 STRINGS 18 FUNCTIONS AND SUBROUTINES - QUICK REFERENCE 21 FUNCTIONS AND SUBROUTINES - REFERENCE 22 REGISTRATION INFORMATION 41 GAPQBDR REGISTRATION 42 INDEX 43 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company DESCRIPTION ----------- GAPQBDR is a professional development kit for Bulletin Board Door programmers. It can also be used to facilitate the writing of stand alone communications programs. Written entirely in Quick Basic (with a little help from some Assembler support routines), it is fast, reliable, easy to use, and easy to incorporate into the serious programmer's source code. Features Include : o Interfaces with GAP Communications and pcboard. o Full communications support. o Supports CTS checking, even at 300 bps, for error free transmissions. o Does not require watchdog or CTTY. o Uses ANSI colors instead of Basic's color statements so the sysop sees what the caller sees. o High speed text file display. o Supports ANSI color and ASCII text files with no programming effort other than to make a single subroutine call. o Easy to use Random Number Generator. o Informative Status Line display. o Monitors keyboard activity and caller time remaining. o Easy interfacing to BBS system and user files. o Sysop chat with full word wrapping. o Allows the sysop to shell to DOS. o "Remembers" the default drive and directory which prevents file access errors. o Credits caller with time spent chatting or while sysop is in a DOS shell. o Sysop can twit caller without caller ever knowing the sysop is watching. o Caller time can be increased or decreased. o Full programmer control of whether or not to update the BBS system files. o Time calculations are not dependent on the "seconds since midnight" and are thus unsusceptible to the midnight roll over. o Timer routines are hardware independent. o Allows the sysop to override the "more" prompt during file shows. o Allows the sysop to "force" a file display. o Automatic detection of multi-user system. o Input routines are consistent throughout the program. o Uses the latest in Quick Basic features. o Extremely easy interfacing to door programs. Page 2 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company GETTING STARTED --------------- GAPQBDR is distributed in archived format. The contents of the archive should be as follows: GAPQBDR.TXT - This documentation. GAPQBDR.QLB - Library routines for QB environment. GAPQBDR.LIB - Standard Library routines for BC. GAPQBDR.BI - Door Interface include file. DOOR.ARC - Sample program illustrating many of the features of GAPQBDR. FIXDTR.TXT - Instructions for making DTR patches. READ.ME - Any pertinent information which you should read. If you purchased the source code to GAPQBDR, the following files are included in an archive called GAPQBSRC: GAPQBDR.BAS - Basic source KEYBRD.ASM - Assembler source for keybrd function. MAKEQBDR.BAT - Batch file for compiling the source modules and creating libraries. QBDRLIB - LIB response file. QBDRQLB - Linker response file. SRCREAD.ME - Any pertinent information which you should read. In addition, you will need the file QB.BI which is distributed with the Microsoft QB disks. You will also need a DTR patched version of BCOM45.LIB and BRUN45.EXE (depending upon how you distribute your executable files). The GAPQBDR module includes routines to turn DTR back on after Basic turns it off when the communications port is closed, however this is an unreliable method of insuring that the modem will not respond to the momentary drop of DTR by dropping carrier. Many modems simply respond too quickly to the split second drop of DTR. It would be nice if Microsoft would leave the communications port they way they found it! Place the files in your QB work directory. Make sure that QB.BI is accessible to the compiler. Throughout this document, the terms function, routine, procedure and subroutine are used interchangeably. However, pay close attention to the return value and the examples. In QB, a function returns a value, where as a sub program does not. If you use an external editor to write your programs, the editor must allow control characters to be entered and displayed. The ANSI constants are initialized by literal characters and if your editor removes the ESC character from the constants, your ANSI displays will be quite messy. Page 3 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company If you are using the QB environment, you will need to load the door module along with your source program. To do so, type the following : QB door /L GAPQBDR (where door is the name of your basic source program) If you fail to load the quick library along with your program, you will receive a great many "subprogram not defined" errors when you try to compile or run your program. We are a firm supporter of declaring all variables prior to their use. Not only does it make your programs easier to debug, it makes them easier to read and follow. We recommend that you follow our guidelines and declare all of your global variables at the beginning of your program, after including GAPQBDR.BI. At the very beginning of your program, you must include the GAPQBDR.BI file. Without this file, nothing will work. It must be the first directive in your source file. To include the file, you type the following at the beginning of you source program: '$INCLUDE: 'GAPQBDR.BI' Do not under any circumstances use the DEF type statements (IE, DEFINT A-Z). This is the lazy persons method of programming. Typedef your variables by either declaring them ahead of time, or by appending the type after the name (IE, A$, I%). If you need to use your own On Error routines, keep in mind that when you initialize the door, the On Error trap will be re- routed. If you subsequently change the Error Trap address, it is your responsibility to deal with any run time errors. The user defined keys of 15, 16, 17, and 18 are reserved for use by GAPQBDR. If you use the ON KEY statement with user defined keys, remember that the above four keys are RESERVED. You are now ready to begin your program. You may now declare and initialize your own variables, initialize your program, or what have you. The first thing that must be done prior to using any of the door functions, is to initialize GAPQBDR itself. This is done by making a call to read.cnf. Read.cnf opens the configuration file (the name of which you pass as a parameter), reads the first two lines of the file, and sets the Error Trap address. If the configuration file cannot be found, the program will end. The format of the configuration file is as follows: ----------------------------------------- c:\gap The Crow's Nest Page 4 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company The first line of the file is the path to the BBS default directory. The second line is the name of the BBS. The configuration file is usually given a name similar to the name of your door program, with a CNF extension. Read.cnf will leave this file open for your use. If you have any configuration options of your own, you may place them in this file beginning with line 3. Do not read your configuration options until after making a call to init.door (which should be the second function call in your program). Upon return from init.door, you are free to read your configuration options (if any). At this time, you should close the configuration file. Its file number is #1. Normally, your program is invoked with a command line parameter giving the name of the configuration file to use: (IE, DOOR DOOR.CNF). You would use the COMMAND$ function to extract the configuration parameter and then pass this parameter on to read.cnf. This allows the end user to use a single program (your program) with multiple configuration files. This is especially important under multi-user systems where separate configuration files are needed. The configuration file is opened as a sequential file so using Line Input #1 would be appropriate for reading any data. If there were no errors, read.cnf will return. You must now make a call to init.door. Init.door uses the information derived from line 1 of the configuration file to open and read DOOR.SYS (GAP) or PCBOARD.SYS (PCB) as well as the BBS configuration file. In addition, init.door opens the communications port (if a remote user is on), initializes some global variables, and initializes the random number generator. If there is an error, init.door will not return. Instead it will end the program. That is basically all you have to do to initialize the GAPQBDR module. When your program ends, you should clean house if necessary and call leave. Leave closes the communications port and any open files, sends a sign off message to the caller, and then exits to DOS. Things to remember: To get the ball rolling, include GAPQBDR.BI as the first directive in your source program. To initialize the door, call read.cnf with the name of your programs configuration file. Call init.door. Call leave when your program is finished. With the exception of file #1 which is used to read the configuration file and which YOU should close, the only other file number which is hard coded is file #9. This is the Page 5 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company communications file. GAPQBDR uses good programming practice by asking Basic for a file number rather than telling Basic which number to use. All input and output should be performed through the GAPQBDR functions. The sample program gives good examples on how to accomplish this. To determine if the BBS is a single or multi user system, check the variable called node. If it is anything other than 0, then the BBS is multi-user and you should read/write your data files with sharing attributes. The default mode of operation is GAP mode. This means that you should not use those functions which access PCB files. To determine if the BBS is a PCB system, check the variable do.pcb. If this is set to 1, then the BBS is PCB and you should not access GAP files. The variable do.pcb is set to 1 if the environment variable GAPQBDR is set equal to PCB. To test your program, you will need a DOOR.SYS (GAP) or a PCBOARD.SYS (PCB) file that was written for local exit. Of course, you can always modify any DOOR.SYS file and change the first line so that it reads COM0:. In addition, for a GAP BBS, the GAPBBS.CNF file must be accessible (PCBOARD.DAT and USERS for PCB). A complete set of sample files are provided for testing your program under local mode. Experience has shown that although the QB environment editor makes for a cumbersome programmers editor, testing programs inside QB is perhaps the easiest and most efficient way to test. The environment is wonderful for catching syntax errors and even more fantastic at allowing the programmer to correct those errors and continue to run the program. COMPILING AND LINKING --------------------- GAPQBDR has already been compiled with the necessary compile time switches. To compile your programs, use whatever switches are required with the following commands : bc doorname; link doorname,,NUL.MAP,+gapqbdr Where doorname is the name of your program. WARNING: Do NOT, under any circumstance, use the /mbf compile time switch. GAPQBDR expects all of its numeric variables to be in IEEE format. If you have a need to Page 6 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company manipulate a PCB data file (which contains MBF format numbers), declare the MBF fields as strings and use either CVSMBF or CVDMBF to convert the strings. You will see an example of this in the record structure for the PCB USERS file. The fields downbytes and upbytes are actually DOUBLES. The field lastmsg is actually a SINGLE. To convert downbytes you can use : downbytes = CVDMBF(pcbuser.downbytes). If you update this field in the PCB USERS file, you can save it by using : pcbuser.downbytes = MKDMBF$(downbytes). The Microsoft Binary format for numbers should never be used. Support for the MBF format will no doubt disappear in future versions of QB. You should ALWAYS use the latest versions and features of your compiler. IEEE Format numbers provide for greater accuracy and wider ranges. They are compatible with assembler and C. They also allow you to use a math coprocessor, if one is available. You should also use LONG INTEGERS instead of SINGLE or DOUBLE precision numbers where appropriate. A long integer can represent a number as great as 2.1 billion! This should more than cover your needs. Especially since a BBS (door) program rarely uses or has a need for real numbers. If you are converting an old door program that uses MBF format numbers in random access files, you will need to use either the QB supplied conversion functions or convert your random access data files to the new user defined binary type record structures. If you purchased the source code to GAPQBDR, there are batch and response files to aid in re-compiling and librarying the source modules. Page 7 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company SYSOP SETUP AND FUNCTIONS ------------------------- These sysop setup and function descriptions should be placed in the documentation of your door program. You should, of course change the setup information to fit your particular needs. Door programs written with the GAPQBDR Door Interface Module will run on GAP Communications version 3 and greater and on PCB version 14 and greater. To configure the door for a particular BBS setup, a configuration file must be used. At the very minimum, this file will contain two lines. It may contain more than two, depending upon a particular doors configuration requirements. The name of the file is usually the same as that of the door program but with a CNF extension. The minimum requirements for the file are as follows: c:\gap The Crow's Nest The first line is the full path to your BBS default directory. For GAP, this is usually C:\GAP. For PCB, this is usually C:\PCB. The second line is the name of your BBS. GAPQBDR will obtain the sysop's name from the BBS configuration file. You must now create a batch file to invoke the door. This batch file is placed in your BBS default directory. Such a batch file might look like this: echo off cd \gap\doors\tl tl tl.cfg cd \gap gap As you can see, the door is invoked by passing the configuration file name as a parameter. You will also need to modify your doors menu files and the data file that tells the BBS what your doors are and the security level needed to access them. For GAP, these are respectively: DOORM DOORMG DOORS.DAT Please refer to your BBS documentation for details on setting these files up. Page 8 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company If you are running multi-nodes, simply create a separate door configuration file for each node, and number them. For instance, for a 3 node system, you might have the following configuration files: TL1.CFG TL2.CFG TL3.CFG The only difference between the three would be the 1st line which points to the default directory for the particular node. Multi-user operation is automatic. For GAP, the presence of DUMMY.LOK in the MAIN directory triggers multi-user operation. For PCB, this information is derived from the PCBOARD.DAT file. The following files are read during door initialization. They must be present or the door will not operate. GAP PCB ---------------- ---------------- DOOR.SYS PCBOARD.SYS GAPBBS.CNF PCBOARD.DAT USERS In addition, a particular door may access the GAP USERS.DAT and GAPDOS.DAT files. The default mode of operation for any door that is developed with GAPQBDR is the GAP mode. To run the door under a PCB BBS, you must set the following environment variable (in UPPERCASE): GAPQBDR=PCB The following sysop functions are available while awaiting keyboard input : F5 - Shell to DOS. F8 - Twit user and return to BBS. F10 - Initiate chat with user. CF10 - Answer user page bell. Home - Main user stats. End - Displays sysop keys available. PgDn - Secondary user stats. Up Arrow - Increase user's time remaining. Dn Arrow - Decrease user's time remaining. One of the nicer features about using the TWIT key, is the user is not told that "the sysop wants them to return to the BBS". Instead, a very plain and simple message of "returning you to the Page 9 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company BBS" is displayed. This way, the user is given no indication that the sysop is hovering about. When using the F5 shell to DOS key, to return to the door program, simply type EXIT at the DOS command prompt. It is not necessary to change directories back to the door directory. GAPQBDR is smart enough to know which drive and directory the door program is in and will reset the defaults upon return from DOS. The Up and Down Arrow keys increase and decrease the user's time respectively by 5 minutes for each press of the key. There is no indication of what is occurring (except by the fact the user's time remaining will change), so the sysop should try not to have a lead finger. The increase or decrease is effective only while the user is in the door. Since we are firm believers that the BBS system files belong to the BBS and should not be altered by any door program, updating the BBS system file is NOT automatic. If you wish that any decrease or increase in the user's time be made permanent, you may, after initializing the door, call the function that opens the system file. Keep track of any time credits during the door programs operation, then call the function that updates the BBS system file. Examples of how to do this are included in the sample program. Page 10 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company GLOBAL VARIABLES ---------------- All global variables (except for constants) are defined as COMMON SHARED. They are included in your program by including the file GAPQBDR.BI at the top of your source file. CONSTANTS --------- Constants are defined as - CONST name = constant value. NO Defined as 0 YES Defined as 1 ANSI CONSTANTS -------------- ANSI constants contain the actual ANSI color sequences. BLACK ANSI codes for Black BLUE ANSI codes for Blue BROWN ANSI codes for Brown CYAN ANSI codes for Cyan GREEN ANSI codes for Green MAGENTA ANSI codes for Magenta RED ANSI codes for Red WHITE ANSI codes for White BBLACK ANSI codes for Grey BBLUE ANSI codes for bright Blue BCYAN ANSI codes for bright Cyan BGREEN ANSI codes for bright Green BMAGENTA ANSI codes for bright Magenta BRED ANSI codes for bright Red BWHITE ANSI codes for bright White YELLOW ANSI codes for Yellow Page 11 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company DOOR.SYS VARIABLES ------------------ DOOR.SYS variables are initialized while reading the Door Interface Module, DOOR.SYS. (For PCB, PCBOARD.DAT and USERS must be read to initialize these variables). These variables are available from door start up to door end. The DOOR.SYS variables are the door programmer's connection to the BBS. INTEGERS -------- alarm Caller Alarm. 0 = off, 1 = on baud DTE rate to open COMM port at bell Page Bell. 0 = off, 1 = on c.olor Color toggle. 0 = no color, 1 = color ok expert Expert mode. 0 = non-expert, 1 = expert l.ocal 0 = remote user, 1 = local level User's security level minsleft Number of minutes user has left at door start node Node number. 0 = single user page User's page length parity Should actually be data bits and is not used port Communications port in use printer Printer Toggle. 0 = off, 1 = on s.creen Screen display. 0 = off, 1 = on userbaud BPS rate of the remote user LONGS ----- downbytes Total bytes downloaded downloads Number of downloads maxbytes Maximum number of bytes allowed to download recnum User's record number in USER file timeson Number of times user has been on upbytes Total bytes uploaded uploads Number of uploads STRINGS ------- bphone User's business or data phone number city User's home town first User's first name hphone User's home phone number last User's last name lastdate Last date user was on password User's password. PASSWORD if sysop is on subscrip Date user's subscription expires username User's full name Page 12 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company GAPQBDR GLOBALS -------------- These variables are the documented, global variables (initialized and used by GAPQBDR). They may be modified and/or used at the programmer's discretion. INTEGERS --------- do.pcb If set to 1, the BBS is a PCB system noup If set to 1, get.string will not uppercase timecredit Time credits for user (in minutes) timeleft Time user has left (in minutes) LONGS ----- starttime Time the user logged on (in seconds) temptime For calculating keyboard time out timenow Time it is now (in seconds) STRINGS ------- anystring1 Global garbage collector bbs.dir Path to BBS default dir board.name Name of the BBS gendir Path to the gen directory maindir Path to the main directory sysname Sysop's name GAPDOS.DAT VARIABLES -------------------- These variables are initialized by the programmer by making a call to read.gapdos. Note that string variables are fixed length and will contain a NULL byte. Please see the GAPQBDR.BI include file for the actual definition of these variables. gapdos.baud DTE bps rate gapdos.callbytes Ttl bytes available for download gapdos.didnew 1 = did a new files scan gapdos.exitdos 1 = exit to DOS after call gapdos.forumnum Forum the user is in gapdos.givetime 1 = event pending, else extra time received gapdos.joined Bit flags of forums joined gapdos.localc 0 = user, 1 = sysop, 2 = local user gapdos.minavail Total minutes available to user gapdos.port Port being used gapdos.starttime Time (in seconds) user logged on Page 13 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company gapdos.timecredit Any time credits user may have gapdos.userbaud User's bps rate gapdos.userfirst User's first name gapdos.userindex User's index into user file gapdos.username User's full name USERS.DAT VARIABLES ------------------- These variables are initialized by the programmer by making a call to read.gapuser. Note that string variables are fixed length and will contain a NULL byte. Please see the GAPQBDR.BI include file for the actual definition of these variables. WARNING : STRING fields are fully padded with spaces and the last position of the string is and MUST be a 0! user.blts Total bulletins read user.bphone User's work or data phone number user.city City, state, and zip (padded) user.curbytes Total bytes downloaded this call user.curdown Total files dowloaded today user.doors Total doors opened user.downloads Total downloads user.expert Novice = N, expert = Y user.fname User's first name (padded) user.handle User's handle (padded) user.hphone User's home phone number user.joined Total forums joined user.lastdate Last date on - mm/dd/yy user.lastdir Date last looked at a directory listing user.lastfrm Last forum in user.lastmsg Last message read user.lasttime Last time on - hh:mm user.level Security Level user.lname User's last name (padded) user.mesleft Total messages left user.mesread Total messages read user.minutes Total minutes last call user.page Page length user.passwd User's password (padded) user.private Allow on private nodes? user.protocol Transfer protocol (padded) user.subscribe Date user's subscription expires user.sysop Sysop record, 1 = Y, 0 = N user.timeson Number of times on user.ttlbytes Total bytes downloaded user.ttlmins Total mins on user.upbytes Total bytes uploaded user.uploads Total uploads Page 14 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company PCBOARD.SYS VARIABLES -------------------- These variables are initialized automatically by init.door if the BBS system is PCB (set by environment variable GAPQBDR=PCB). pcbsys.baud Com port bps rate pcbsys.calleralarm Caller alarm -1=on,0=off pcbsys.colorc Color toggle Y,N,7 pcbsys.ctime Time user logged on as HH:MM pcbsys.display Display on/off -1=on,0=off pcbsys.eactive Event active -1=yes,0=no pcbsys.errcorrect ECC modem -1=yes,0=no pcbsys.event Event time as HH:MM pcbsys.forumnum Forum user was in "0" = main pcbsys.minsleft Minutes left for caller pcbsys.node Node number as short integer pcbsys.pagebell Page bell -1=on,0=off pcbsys.password User's password pcbsys.port Com port as "0","1", or "2" pcbsys.printer Printer on/off -1=on,0=off pcbsys.sevent Slide event -1=yes,0=no pcbsys.sysopnext Sysop on next N,X,space pcbsys.timeallowed Allowed time in minutes pcbsys.timecredit Any time credits in minutes pcbsys.timegiven Highest forum time given pcbsys.timeon Time user logged on in minutes pcbsys.timeused Time user has used that day pcbsys.ttlbytes Total K bytes available pcbsys.userbaud Caller bps rate (Local if local mode) pcbsys.userfirst User's first name pcbsys.username Name of caller pcbsys.userrec User's record number PCB USERS VARIABLES ------------------- These variables are initialized automatically by init.door if the BBS system is PCB (set by environment variable GAPQBDR=PCB). To utilize downbytes, upbytes, and lastmsg you must use the QB Microsoft Binary Format conversion functions. pcbuser.bphone User's work or data phone number pcbuser.city City, state, and zip (padded) pcbuser.cnfregis Forum registration pcbuser.delete Delete, Y=yes,N=no pcbuser.downbytes Total download bytes. Use CVDMBF pcbuser.downloads Number of downloads pcbuser.expert Expert mode Y=yes,N=no pcbuser.hphone User's home phone pcbuser.lastconf Last forum in Page 15 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company pcbuser.lastdate Last date user was on pcbuser.lastdir Last New files scan pcbuser.lastime Last time user was on pcbuser.lastmsg Last message read in main. Use CVSMBF pcbuser.lastmsg1 Last message read in each forum pcbuser.level User's level as short integer pcbuser.name User's name pcbuser.page Page length pcbuser.passwd User's password pcbuser.protocol Protocol type pcbuser.regisdate Registration date pcbuser.timeson Number of times on pcbuser.upbytes Total upload bytes. Use CVDMBF pcbuser.uploads Number of uploads Page 16 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company GLOBAL VARIABLES - ALPHABETICALLY By Type ----------------------------------------- CONSTANTS --------- BBLACK ANSI codes for Grey BBLUE ANSI codes for bright Blue BCYAN ANSI codes for bright Cyan BGREEN ANSI codes for bright Green BLACK ANSI codes for Black BLUE ANSI codes for Blue BMAGENTA ANSI codes for bright Magenta BRED ANSI codes for bright Red BROWN ANSI codes for Brown BWHITE ANSI codes for bright White CYAN ANSI codes for Cyan GREEN ANSI codes for Green MAGENTA ANSI codes for Magenta NO Defined as 0 RED ANSI codes for Red WHITE ANSI codes for White YELLOW ANSI codes for Yellow YES Defined as 1 INTEGERS -------- alarm Caller Alarm. 0 = off, 1 = on baud DTE rate to open COMM port at bell Page Bell. 0 = off, 1 = on c.olor Color toggle. 0 = no color, 1 = color ok do.pcb 1 = This is a PCB system expert Expert mode. 0 = non-expert, 1 = expert gapdos.baud DTE bps rate gapdos.forumnum Forum the user is in gapdos.givetime 1 = event pending, else extra time received gapdos.localc 0 = user, 1 = sysop, 2 = local user gapdos.minavail Total minutes available to user gapdos.port Port being used gapdos.timecredit Any time credits user may have gapdos.userbaud User's bps rate l.ocal 0 = remote user, 1 = local level User's security level minsleft Number of minutes user has left at door start node Node number. 0 = single user noup 1 = get.string will not uppercase page User's page length parity Should actually be data bits and is not used pcbsys.minsleft Minutes left for caller pcbsys.timeallowed Allowed time in minutes pcbsys.timecredit Any time credits in minutes pcbsys.timegiven Highest forum time given pcbsys.timeon Time user logged on in minutes Page 17 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company pcbsys.timeused Time user has used that day pcbsys.ttlbytes Total K bytes available pcbsys.userrec User's record number pcbuser.downbytes Total download bytes. Use CVDMBF pcbuser.timeson Number of times on pcbuser.uploads Number of uploads port Communications port in use printer Printer Toggle. 0 = off, 1 = on s.creen Screen display. 0 = off, 1 = on timecredit Time credits for user (in minutes) timeleft Time user has left (in minutes) user.curdown Total files dowloaded today user.lastfrm Last forum in user.level Security Level user.minutes Total minutes last call user.page Page length userbaud BPS rate of the remote user LONGS ----- downbytes Total bytes downloaded downloads Number of downloads gapdos.callbytes Ttl bytes available for download gapdos.joined Bit flags of forums joined gapdos.starttime Time (in seconds) user logged on maxbytes Maximum number of bytes allowed to download recnum User's record number in USER file starttime Time the user logged on (in seconds) temptime For calculating keyboard time out timenow Time it is now (in seconds) timeson Number of times user has been on upbytes Total bytes uploaded uploads Number of uploads user.blts Total bulletins read user.curbytes Total bytes downloaded this call user.doors Total doors opened user.downloads Total downloads user.joined Total forums joined user.lastmsg Last message read user.mesleft Total messages left user.mesread Total messages read user.timeson Number of times on user.ttlbytes Total bytes downloaded user.ttlmins Total mins on user.upbytes Total bytes uploaded user.uploads Total uploads STRINGS ------- anystring1 garbage collector bbs.dir Path to BBS default dir board.name Name of the BBS Page 18 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company bphone User's business or data phone number city User's home town first User's first name gapdos.didnew 1 = did a new files scan gapdos.exitdos 1 = exit to DOS after call gapdos.userfirst User's first name gapdos.userindex User's index into user file gapdos.username User's full name gendir Path to the gen directory hphone User's home phone number last User's last name lastdate Last date user was on maindir Path to the main directory password User's password. PASSWORD if sysop is on pcbsys.baud Com port bps rate pcbsys.calleralarm Caller alarm -1=on,0=off pcbsys.colorc Color toggle Y,N,7 pcbsys.ctime Time user logged on as HH:MM pcbsys.display Display on/off -1=on,0=off pcbsys.eactive Event active -1=yes,0=no pcbsys.errcorrect ECC modem -1=yes,0=no pcbsys.event Event time as HH:MM pcbsys.forumnum Forum user was in "0" = main pcbsys.node Node number as short integer pcbsys.pagebell Page bell -1=on,0=off pcbsys.password User's password pcbsys.port Com port as "0","1", or "2" pcbsys.printer Printer on/off -1=on,0=off pcbsys.sevent Slide event -1=yes,0=no pcbsys.sysopnext Sysop on next N,X,space pcbsys.userbaud Caller bps rate (Local if local mode) pcbsys.userfirst User's first name pcbsys.username Name of caller pcbuser.bphone User's work or data phone number pcbuser.city City, state, and zip pcbuser.cnfregis Forum registration pcbuser.delete Delete, Y=yes,N=no pcbuser.downloads Number of downloads pcbuser.expert Expert mode Y=yes,N=no pcbuser.hphone User's home phone pcbuser.lastconf Last forum in pcbuser.lastdate Last date user was on pcbuser.lastdir Last New files scan pcbuser.lastime Last time user was on pcbuser.lastmsg Last message read in main. Use CVSMBF pcbuser.lastmsg1 Last message read in each forum pcbuser.level User's level as short integer pcbuser.name User's name pcbuser.page Page length pcbuser.passwd User's password pcbuser.protocol Protocol type pcbuser.regisdate Registration date pcbuser.upbytes Total upload bytes. Use CVDMBF subscrip Date user's subscription expires Page 19 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company sysname Sysop's name user.bphone User's work or data phone number user.city City, state, and zip (padded) user.expert Novice = N, expert = Y user.fname User's first name (padded) user.handle User's handle (padded) user.hphone User's home phone number user.lastdate Last date on - mm/dd/yy user.lastdir Date last looked at a directory listing user.lasttime Last time on - hh:mm user.lname User's last name (padded) user.passwd User's password (padded) user.private Allow on private nodes? user.protocol Transfer protocol (padded) user.subscribe Date user's subscription expires user.sysop Sysop record, 1 = Y, 0 = N username User's full name Page 20 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company FUNCTIONS AND SUBROUTINES - QUICK REFERENCE ------------------------------------------- a.ccess% Checks for the existence of a file. ansi Displays ANSI escape sequences. backspace Sends one or more backspaces. ckeypress% Checks for a remote or local key press. clear.scr Clears the local and remote screens do.chat To allow sysop to chat with remote user. elap.time Computes elapsed time. get.string Gets a string of characters. get.time& Returns number of seconds since 01/01/70. getakey% Gets one key responses. getrand% Returns a random number. init.door Initializes the Door. leave Shuts down door and returns to the BBS. more Checks for a full screen. nl Sends a CR/LF to local and remote. no.carrier Prints a message if carrier lost. open.gap% Opens and reads GAPBBS.CNF. pagesysop Alerts sysop that the user wants to chat. pause Sends a "Press [Any Key] To Continue" prompt. putachar Sends a single character. putkey Used by chat for word wrapping. read.cnf Reads the door configuration file. read.doorsys% Reads DOOR.SYS. read.gapdos% Reads GAPDOS.DAT. read.gapuser% Reads USERS.DAT. read.pcbsys% Reads PCBOARD.SYS. read.pcbuser% Reads PCB USERS file. right.trim$ Trims spaces from string. set.status Displays status line. show.file Displays text files. show.mess Displays a message. time.credit Gives credits for time used. time.left Computes time remaining. update.clock Updates status line clock. waitasec Pauses for x number of seconds. wrap.word Wraps a word. write.gapdos% Writes GAPDOS.DAT. write.gapuser% Writes USERS.DAT. write.pcbsys% Writes PCBOARD.SYS. write.pcbuser% Writes PCB USERS. Page 21 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company FUNCTIONS AND SUBROUTINES - REFERENCE ------------------------------------- Functions always return a value. The type of the return value is denoted by the type modifier after a function name. The return value should be assigned to a variable of the same type. For instance, the function get.time& returns a long integer. To re- trieve the return value, assign it to an long integer as : long.int& = get.time& Subroutines do not return a value. To call a subroutine, use the Basic CALL function : call get.string Name : a.ccess% Purpose : Checks for the existence of a file. Parameters : Full path and name of file Return Value : 0 = file was found, 1 = file not found Description : In order to avoid Basic errors that occur when trying to open a file that does not exist, this function should be used prior to opening any file. Example : r% = access%("GAPQBDR.DOC") if r% <> 0 then print "Cannot Find GAPQBDR.DOC" end if Name : ansi Purpose : Displays ANSI escape sequences Parameters : ANSI color to display Return Value : None Description : This function will send a string of ANSI escape sequences to the remote user and to the local console. The ANSI codes for the various colors are defined as constants in the GAPQBDR.BI file. If the remote or local user is in non graphics mode, the function returns immediately. Example : call ansi(BWHITE) Page 22 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company Name : backspace Purpose : Sends one or more backspaces Parameters : Number of backspaces to send Return Value : None Description : In order to actually erase a character on the screen, you must send a 3 character sequence which consists of backspace, space, backspace. This function will send as many of these 3 char- acter sequences as you specify in the parameter list. Example : call backspace(1) str$ = "Press Any Key " ' set up string call show.mess(str$,NO,NO) ' show string c% = getkeyc% ' get a key call backspace(len(str$)) ' erase string Name : ckeypress% Purpose : Checks for a remote or local key press Parameters : None Return Value : 0 = no key is waiting, 1 = a key is waiting Description : This function will check the local keyboard as well as the communications receive buffer to see if a key is waiting to be read. It is most often used in loops that need to receive a 1 character keystroke. Example : c% = ckeypress% ' key pressed? c% = 0 ' initialize do | ' do something | c% = ckeypress% ' key pressed? until c% <> 0 ' key pressed,exit Name : clear.scr Purpose : Clears local and remote screens. Parameters : None Return Value : None Description : This routine will use the Basic CLS 2 statement to clear the local screen. If the remote caller is in non-color mode, it sends a CHR$(12) to the remote screen, otherwise it sends the ANSI clear screen sequence. Example : call clear.scr ' clear screen Page 23 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company Name : do.chat Purpose : To allow sysop to chat with remote user Parameters : None Return Value : None Description : This function allows a one on one chat with a re- mote user. If the caller is in graphics mode, the sysop's key presses will be displayed in green and the remote user's key presses will be displayed in white. Text will automatically wrap at column 76. To exit chat, press either the ESC key or type a CTRL-X. Note that the user may also send these characters to end chat. The user will receive full credit for the time spent chat- ting with the sysop. However, this function will not update the BBS system file so it is possible that the user may be logged off (with an out of time message) when he/she returns to the BBS. Example : call do.chat response$ = " " ' initialize call get.string(response$) ' get a string if response$ = "P" then ' paging sysop call do.chat ' chat with sysop end if Name : elap.time Purpose : Computes elapsed time while waiting for keyboard input Parameters : None Return Value : None Description : This function is used in loops that await a key- board response. Prior to entering the loop, the variable called temptime should be initialized with the current time. Once inside the loop, this function should be called to keep track of the elapsed time. If there is no keyboard response within 4 minutes, the user will be logged off. Example : call elap.time temptime& = get.time& ' start timer do gc = getakey% ' get a key if gc <> 0 then ' key pressed exit do ' exit and process end if call elap.time ' activity? loop ' continue Page 24 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company Name : get.string Purpose : Gets a string of characters Parameters : String to fill Return Value : None Description : This is the main input routine. It will get a string from either the remote user or the local keyboard. The string passed will be set to the characters received. The length of the input string is determined by the length of the string passed. Do not pass a fixed length string to this routine. Before calling, you must initialize the passed string with spaces. The number of spaces in the string determines the number of characters al- lowed to be input. If a user attempts to type more characters than allowed, the cursor will not move pass the end of the string. Input ends when the Enter key is pressed. To initialize the string, use the Basic space$ function (IE, input$ = space$(10) - initializes input$ to 10 spaces). WARNING : It is extremely important that the passed string be initialized. Failure to set the string to spaces, will cause unpredictable results! This function does not return a new string con- taining the keyboard input. Instead, it modifies the string you pass to it in the parameter list. The string will be stripped of any trailing spaces. get.string automatically uppercases the string. If you wish to disable this feature, set the variable noup to 1. get.string will automatically check for keyboard activity so it is not necessary for you to do so. Example : instr$ = space$(10) ' initialize call get.string(instr$) ' get string Page 25 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company Name : get.time& Purpose : Gets the number of seconds elapsed since 01/01/70 Parameters : None Return Value : Number of seconds since 01/01/70 Description : This routine is equivalent to the C time() func- tion. It is used throughout the GAPQBDR module to compute various times. This function is not sus- ceptible to the midnight roll over problem so prevalent in Basic communications programs. Note that the return value is of type LONG. You must cast the return value to a LONG INTEGER or loss of significant digits will result. Example : dim ltime as long ' declare as long ltime = get.time& ' get the time ' if you don't like declaring variables, you can ' do it the old fashioned way longtime& = get.time& ' get the time Name : getakey% Purpose : Gets one key responses Parameters : None Return Value : ASCII code for the key pressed or 0 Description : This is the main keyboard input routine (internal). It is called by get.string as well as any keyboard polling loops. It checks the re- ceive buffer as well as the local keyboard for a key press. If one is not found it returns 0. The character input is not echoed. Since 99% of all keyboard input comes from this routine, it checks for carrier, time remaining, keyboard time-out, as well as special sysop function keys. The "timeleft" variable is updated via this rou- tine. This is the variable you would normally use in a prompt such as, [20 mins left] Main Command : Example : c% = getakey Page 26 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company Name : getrand% Purpose : Gets a random number Parameters : Low number, high number Return Value : A random number Description : This routine is provided because it is much easier to use and understand than Basic's random function. Provide as parameters two integers. The first parameter is the lowest number you will accept as a random number, and the second parame- ter is the highest random number you will accept. The function will return a random integer between the range specified (low and high are included in the range of numbers). It is not necessary to seed the random number generator as this is done automatically for you during program initialization. Example : rndnum% = getrand% (1,10) ' get a random ' number between 1 ' and 10 Name : init.door Purpose : Initializes the GAPQBDR functions Parameters : None Return Value : None Description : This routine must be called immediately after calling read.cnf. It initializes the door, opens and reads system files, initializes the comm port, initializes global variables and in gen- eral, makes sure that all of the files required for operation are present. There is no return value. If an error occurs while trying to ini- tialize, the function will display an error mes- sage and end the program. Example : call read.cnf("DOOR.CFG") ' read config file call init.door ' init the door Name : leave Purpose : Exits the program Parameters : None Return Value : None Description : When the program terminates, it must call this function to end. This is the ONLY proper exit from the door. Example : call leave Page 27 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company Name : more Purpose : Checks for a full screen and issues a More Prompt Parameters : None Return Value : None Description : This is an internal routine that is called by the character output functions. Example : Name : nl Purpose : To send a Carriage Return and Line Feed to local and remote Parameters : Number of New Line's to send Return Value : None Description : To send a blank line, call this routine with the number of blank lines you wish to send. Example : call nl(2) ' send two blank ' lines Name : no.carrier Purpose : Prints a message and calls leave() Parameters : None Return Value : None Description : Internal routine that is called when there is a loss of carrier. Displays a message to the local screen and then calls leave to terminate the program. If you have a routine that checks for carrier and you wish to display the standard "No Carrier" message and log the user off, call this function. Example : call no.carrier Name : open.gap% Purpose : Opens and reads the GAPBBS.CNF file Parameters : None Return Value : 0 = no error, 1 = error Description : This function is called by init.door. It opens and reads the configuration file for GAP. Note that only part of the CNF file is read. The main purpose for reading the file is to obtain the path to the BBS's main directory and get the sysop' name. Example : c% = open.gap% Page 28 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company Name : pagesysop Purpose : Alerts sysop that user wants to chat Parameters : None Return Value : None Description : Allows the programer to provide the user with a Page Sysop command. The page lasts for 30 seconds and can be aborted by typing CTRL K. If the sysop's page bell is on, the sysop's speaker will also sound. To answer the page, the sysop should press CTRL F10. Example : response$ = " " ' initialize var call get.string(response$) ' wait for a key if response$ = "P" then ' wants to chat call pagesysop ' tell sysop end if Name : pause Purpose : Sends a "Press [Any Key] To Continue" prompt Parameters : None Return Value : None Description : This function sends a pause prompt and waits for a key press. Example : call nl(1) ' send blank line call pause ' wait for a key Name : putachar Purpose : Send a single character to local and remote Parameters : ASCII character to send Return Value : None Description : This routine is called a "semi-unfiltered" char- acter output routine because it allows for most ASCII characters to be output. Example : c% = ASC("A") ' send an 'A' call putachar(c%) ' to local and ' remote screen c% = getakey% ' get a keypress if (c% <> 0 then ' if we got a key call putachar(c%) ' display the end if ' character Page 29 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company Name : putkey Purpose : Used by chat routines to keep track of word wrapping Parameters : Character to send Return Value : None Description : This is the main output routine for the chat functions. It keeps track of the current column, and decides when it is time to wrap a word. It should not be called by the programmer's routines since putachar is faster and more efficient. Example : Name : read.cnf Purpose : To read the door configuration file Parameters : Full path and file name to the configuration file. Return Value : None Description : Opens the configuration file for the current door. Normally the passed parameter is the name of the door with a .CNF extension (it is assumed that the file is in the same directory as the door program). If an error occurs, the program ends immediately. WARNING : The first two lines of this configura- tion file belong to the GAPQBDR interface module. You are free to use the information, but the in- formation contained in the first two lines must conform exactly to the following specifications. The first line of this file is the full drive and path to the BBS default directory. This is the directory where the BBS system files can be found (IE, GAPDOS.DAT, DOOR.SYS, GAPBBS.CNF). The en- try on line 1 is not checked until init.door is called. The second line of this file is the name of the BBS. It is the responsibility of the door author to describe the format of these two lines to the end user. It is also the responsibility of the door author to insure that the end user have these two lines in the door configuration file. If your door program requires no configuration parameters of its own, you can simply distribute a sample "door".cnf file with these two lines already in it. Page 30 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company GAPQBDR will NOT close this file (file #1) after reading the first two lines. It leaves the file open for the programmer's use. If your door does require certain configuration parameters, have your users place the parameters in the file starting with line 3. If you use a set up pro- gram, be sure that your set up program writes the first two lines as specified. After you have called read.cnf and init.door, if you have any configuration options in the "door".cnf file, you should line input those op- tions. Then close file #1. Even if you have no options to read, close the file. WARNING : You MUST call this routine before using any of the GAPQBDR functions. After calling this routine, you MUST call init.door. Example : call read.cnf("TOURIST.CNF") call init.door Name : read.doorsys% Purpose : Reads the DOOR.SYS universal door interface file Parameters : None Return Value : 0 = no error, 1 = error Description : Internal routine called by init.door. Reads the DOOR.SYS file and initializes any global vari- ables that depend on the information in that file. Example : c% = read.doorsys% Name : read.gapdos% Purpose : Reads the GAP Communications DOS file. Parameters : None Return Value : 0 = no error, 1 = error Description : Reads the GAPDOS.DAT remote exit to DOS file. If you have a need for the information in this file, or if you need to modify the record variables, this function will read the file for you. The record variables are contained in a variable called gapdos. WARNING : Do NOT modify the string fields in GAPDOS.DAT. If the gapdos.userindex field is changed, GAP will be unable to find the user in the userfile upon return from the door. The only proper way to update this file is to Page 31 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company first read it. Make any changes to the variables themselves or use your own temporary variables. Then call write.gapdos to update the record. Example : c% = read.gapdos% Name : read.gapuser% Purpose : Reads the GAP Communications USERS.DAT file Parameters : None Return Value : 0 = no error, 1 = error Description : Reads the user record of the current user in the GAP USERS.DAT file. The record variables are contained in a variable called user. Example : c% = read.gapuser% Name : read.pcbsys% Purpose : Reads the PCBOARD.SYS file. Parameters : None Return Value : 0 = no error, 1 = error Description : For a PCB setup, this function is automatically called by init.door. Do not use unless do.pcb is set to 1. Example : c% = read.pcbsys% Name : read.pcbuser% Purpose : Reads the PCB USERS file. Parameters : None Return Value : 0 = no error, 1 = error Description : For a PCB setup, this function is automatically called by init.door. Do not use unless do.pcb is set to 1. Note that to change the fields downbytes, upbytes, or lastmsg, you will need to use the QB functions CVSMBF or CVDMBF. Example : c% = read.pcbuser% Name : right.trim$ Purpose : Trims spaces from the end of NULL terminated strings Parameters : String containing the spaces. Return Value : String without the spaces. Description : This function will remove the NULL and trim any spaces from the right end of any 'C' string. Example : username$ = right.trim$(gapdos.username) Page 32 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company Name : set.status Purpose : To display and update the sysop status line Parameters : 0 = set the status line, 1 = update the status line, 4 = show other user stats Return Value : None Description : This routine is used internally. There should be no reason to call it unless you have modified a user's stats and you need to update those stats on the status line. In this case, you should use option 0. Example : call set.status(0) Name : show.file Purpose : To display a text file Parameters : The full path and file name to the file to be shown Return Value : None Description : Many door programs have welcome, news, exit, help and other files to show to the user at various points in the program. This is the function that allows you to do that. This function tries to be as intelligent as it possibly can in determining the sysop's wishes. To display a file to the user, call the function with the full drive\path\filename of the file to display. If you have color and non-color versions of files pass the name of the non-color version as this function will automatically append a "G" to the filename if the user is in color mode. In fact, this function will ALWAYS try to find a file with a "G" appended to the end of the name (if the user is in color mode) before it looks for the actual file by the name you specified. If you pass "WELCOMEG" to this function and the user is in color mode, it will first try to find a file with the name of "WELCOMEGG". As with GAP Communications, your text files can have certain control characters as the first character in the file. A "{" signals that the more prompt should never display. In other words, GAPQBDR will not keep track of the number of lines displayed and will never issue a more prompt. This is useful for very long ANSI files. A "@" signals that the pause prompt should be displayed when the screen is full instead of a more prompt. This is very handy when you want the user to see the file in its entirety. The user will not be allowed to break out of the file Page 33 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company read. WARNING : The "{" or "@" MUST appear as the VERY first character in the file. If you use an ANSI editor, be aware that the first few characters in a file will usually be an ANSI color sequence. You normally have to edit the file with a text editor to insert the control character. Because QB 4.x is EXTREMELY slow when it comes to function calls, all input and output is done "in line". Despite QB's high overhead, this function is pretty fast. GAPQBDR does not have GAP's ability to protect the status line. Because of this, it is possible for an ANSI file that contains clear screen codes to erase the status line. At the end of the function, the status line will be re-drawn just in case. Since most ANSI files contain the clear screen codes at the beginning of the file, show.file will remove any such codes during the first read of the file. Pressing CTRL K or CTRL X will abort any file display if the file does not begin with a "@". REMEMBER : If you have both color and non-color versions of the same files, pass the name of the non-color version. Also, the actual disk files must be named in such a way that they have no file extension and the color version ends with a "G". Example : call show.file("WELCOME") call show.file("C:\GAP\GEN\WELCOME") Page 34 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company Name : show.mess Purpose : Displays a message Parameters : Message, ring the bell, issue a New Line Return Value : None Description : Finally! After all of this, just how do you dis- play a message to the user? Well, here it is. This is the string output function for GAPQBDR. Under most circumstances, this is the one func- tion that you would call to display output to the user. There should be no reason to ever call putkey or putachar, as they are basically inter- nal routines. There should be no reason to EVER use the Basic print statement unless you need to display a mes- sage to the local screen that you do not want the remote user to see. In other words, ALL string output should be done through this function. If there is a reason to display information locally it would be much easier and more efficient to keep track of the l.ocal variable, set it to 1, call show.mess with the strings to be displayed, then restore the l.ocal variable to what it was before, instead of using the print function which cannot display ANSI sequences (forcing you to translate ANSI codes to color statements). The three parameters are : 1 - the string to display 2 - YES or NO if you want to sound the remote user's bell. 3 - YES or NO if you want to issue a CR/LF after displaying the string. Page 35 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company Example : ' the first show.mess displays the string and ' leaves the cursor on the same line. The second ' show.mess displays the string, rings the remote ' user's bell, and drops the cursor to the next ' line. call nl(1) call show.mess("Are you ready? (Y/N) : ",NO,NO) a$ = space$(3) call get.string(a$) if left$(a$,1) = "Y" then ' begin whatever it is you want to begin else call nl(1) call show.mess("Too Bad!",YES,YES) end end if Name : time.credit Purpose : Keeps track of time and credits the user with time elapsed Parameters : 1 = start timer, 0 = end timer Return Value : None Description : This is basically an internal routine called by chat and sysop shell to DOS so that the user is not penalized for time used. It updates a global variable called timecredit. Timecredit is used in the calculations that determine the user's time remaining. If you wish to use this feature in your own rou- tines, prior to entering your routine, call time.credit with a 1 and it will start the timer. When your routine is finished, call time.credit with a 0 and the timer will stop. The variable timecredit will be updated with the elapsed time. Example : call time.credit(1) ' start the timer call do.chat ' chat with user call time.credit(0) ' stop the timer ' Note that this is simply an example. do.chat ' calls time.credit on its own. In the above ' example, if the sysop chat with the user took ' 10 minutes, the user will be credited with ' that 10 minutes as will be reflected in the ' timecredit variable. Page 36 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company Name : time.left Purpose : To compute the user's time remaining Parameters : None Return Value : None Description : This is the routine that is called by the input and output routines to compute the user's time remaining. It is not necessary for the programmer to call this routine directly. A global variable called timeleft will be updated with each call. This variable may be used in prompts that display the user's remaining time. As long as all input/output is performed thru calls to the GAPQBDR library, the timeleft vari- able will always be current. Example : call time.left Name : update.clock Purpose : Updates the status line clock Parameters : None Return Value : None Description : Internal routine to update the status line clock. Example : Name : waitasec Purpose : Pauses for the number of seconds specified. Parameters : Number of seconds to pause Return Value : None Description : This function allows you to pause all processing for the specified number of seconds. It is in- sensitive to processor speed and is immune to the midnight rollover problem. Example : call waitasec(10) ' pause for 10 sec Name : wrap.word Purpose : To wrap a word during sysop chats Parameters : None Return Value : None Description : Internal function called by putkey to wrap words. Example : Page 37 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company Name : write.gapdos% Purpose : Updates the GAPDOS.DAT file Parameters : None Return Value : 0 = no error, 1 = error Description : This function allows the programmer to update the GAP Communications remote exit to DOS system file. If the GAPDOS.DAT file is read at door be- ginning, the timecredit variable assigned to gapdos.timecredit, and the GAPDOS.DAT file writ- ten out at doors end, the user will be credited with any time spent during a sysop chat or shell to DOS. Example : c% = read.gapdos% ' read the file if c% = 0 then ' if no error... timecredit = gapdos.timecredit ' do some processing ' give the user 20 more minutes timecredit = timecredit + 20 gapdos.timecredit = timecredit c% = write.gapdos% ' update the file end if Name : write.gapuser% Purpose : Updates the user record in GAP's USERS.DAT file Parameters : None Return Value : 0 = no error, 1 = error Description : This function allows you to update any variables in the GAP USERS.DAT file for the current user. WARNING : The GAP USERS.DAT file contains C char- acter arrays. These are equivalent to Basic's fixed length strings with the exception that the C strings have a NULL character (chr$(0)) in the last position. If you modify any of these fixed length strings, you MUST make sure that the string is fully padded with spaces and that the NULL character is placed in the last string posi- tion. When assigning a value to a fixed length string, Basic will automatically pad the fixed length string with spaces. All the programmer need to is insure that the NULL is inserted at the end of the string. WARNING : The index for the user file consists of the user's last name and first name. Do not un- der any circumstances modify either of these two fields. Doing so will cause corruption of the Page 38 GAPQBDR (C) Copyright 1988,1989 The GAP Development Company Index file. Example : ' give the user a level of 50 c% = read.gapuser% ' 1st read record user.level = 50 c% = write.gapuser% ' update the rec ' allow user to change handle c% = read.gapuser% if c% = 0 then call show.mess("Enter New Handle : ",NO,NO) handle$ = space$(15) call get.string(handle$) if handle$ <> "" then user.handle = handle$ mid$(user.handle,16,1) = chr$(0) c% = write.gapuser% if c% = 0 then show.mess("Saved new Handle",NO,YES) end if end if end if Name : write.pcbsys% Purpose : Updates the PCBOARD.SYS file Parameters : None Return Value : 0 = no error, 1 = error Description : This function allows the programmer to update the PCBOARD.SYS File. Do not use unless do.pcb is set to 1. Example : c% = write.pcbsys% ' write the file Name : write.pcbuser% Purpose : Updates the PCB USERS file Parameters : None Return Value : 0 = no error, 1 = error Description : This function allows the programmer to update the PCB USERS File. Do not use unless do.pcb is set to 1. Note that you will need to use MKSMBF on the field lastmsg, and MKDMBF on the fields downbytes and upbytes, if you modified these fields since reading the file. Example : c% = write.pcbuser% ' write the file Page 39 GAPQBDR LICENSE AGREEMENT ------------------------- This legal document is an agree- GAP Development Company consents ment between you, the end user, in writing, in advance. and GAP Development Company. By using the GAPQBDR software Registration of the SOFTWARE is (the "SOFTWARE") provided by GAP REQUIRED as a condition of use. Development Company, you agree to become bound by the terms of You are granted a royalty-free this agreement, which includes right to distribute executable the software license and the files created using the SOFT- disclaimer of warranty. WARE. You may not, under any circumstances distribute any This agreement constitutes the part of the SOFTWARE with your complete agreement between you executable files. and GAP Development Company. If you do not agree to the terms of If you purchased the SOFTWARE this agreement, promptly return SOURCE CODE, you are granted a the disks and other items that nonexclusive, personal, non- are part of this product. transferable, nonassignable li- cense to use and modify the The SOFTWARE may not be copied, SOURCE CODE and to distribute reproduced, disclosed, trans- your programs. You may not re- ferred, or reduced to any form, produce or distribute the SOURCE including electronic medium or CODE except in executable form machine readable form, or trans- as part of your executable file. mitted or publicly performed by If you distribute your source any means, electronic or other- code, you may not include the wise, unless GAP Development SOFTWARE SOURCE CODE as part of Company consents in writing, in your product. advance. This License is effective until Th SOFTWARE contains valuable terminated. This License will trade secrets and proprietary terminate automatically if you information and is protected by fail to comply with any provi- federal copyright laws. Unautho- sion of this License. rized use of the software can result in civil damages and SUMMARY OF LIMITED WARRANTY: criminal prosecution. In summary, the SOFTWARE is li- You may use the SOFTWARE on a censed AS IS. THERE ARE NO single computer only. You may WARRANTEES, EXPRESS OR IMPLIED, not network the SOFTWARE or oth- INCLUDING BUT NOT LIMITED TO THE erwise use it on more than one IMPLIED WARRANTIES OF MER- computer or terminal at the same CHANTABILITY AND FITNESS FOR A time. PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND YOU MAY NOT COPY the SOFTWARE SPECIFICALLY DISCLAIMED. IN NO except to place the programs EVENT SHALL GAP DEVELOPMENT COM- onto your hard disk and to make PANY BE RESPONSIBLE FOR ANY IN- archival backup copies onto DIRECT, SPECIAL, INCIDENTAL OR floppy disks for your personal CONSEQUENTIAL DAMAGES OR LOST use as permitted by this Li- PROFITS TO YOU OR ANY OTHER PER- cense. You may not copy the SON OR ENTITY REGARDLESS OF THE written materials accompanying LEGAL THEORY, EVEN IF WE HAVE the software. You may not grant BEEN ADVISED OF THE POSSIBILITY sublicenses nor transfer the OF SUCH DAMAGE. SOFTWARE or related materials in any form to any person unless REGISTRATION INFORMATION ------------------------ GAPQBDR is a user-supported program, also known as 'shareware'. Shareware is a means by which users may 'test- drive' software before purchasing. Generally, it allows the user to evaluate the software for a period of 30 days. After the evaluation period the user must either register the product or cease using it. You are permitted under the terms of the above License Agreement to use GAPQBDR for a period of 30 days without payment. If you continue to use the product past the 30 day evaluation period, you must register your copy as described below. Commercial use of this software absolutely requires a registration within the 30 day period. Commercial use includes any software written by you which utilizes GAPQBDR and which you charge any sum of money for the use of your software. This includes shareware registration, donations, registration fees, or any method you use or devise to solicit funds from the users of your software. Commercial use also includes bundling GAPQBDR with other software even if that other software does not utilize any of the GAPQBDR functions. This type of commercial use is strictly prohibited. A great deal of time, money, and effort went into creating GAPQBDR. Unlike other libraries of this type, GAPQBDR was written from scratch and does not have as a basis, "borrowed code". We have utilized many of the latest features of the Quick Basic compiler and wrote critical sections in assembler for speed. Registration of GAPQBDR is a one time fee of $25.00. Payment of this fee entitles you to one year of free upgrades, product support, the right to use GAPQBDR in any executable program you sell or distribute, and a good conscience. Source code is available to registered users for a one time license fee of $25.00. The source code is fully commented and well structured. GAPQBDR Support Board : The Crow's Nest BBS (714)493-3819 Node 1 (714)493-9851 Node 2 GAPQBDR REGISTRATION -------------------- Please fill in and detach the following sheet and mail it to GAP Development Company. ------------------------------------------------------------ I understand and accept the GAPQBDR License Agreement. Accepted By : ____________________________________ (signature) Accepted By : ____________________________________ (printed name) Date : ____________ Product : GAPQBDR Licensee Information : Name : ___________________________________________ Address : ___________________________________________ Address : ___________________________________________ City,State,Zip : ___________________________________________ Voice Phone : ________________________ ------------------------------------------------------------ # Description Price ------------------------------------------------------------ 2001 GAPQBDR Run Time Library 25.00 __________ 2002 GAPQBDR Source Code License 25.00 __________ Total Due __________ Less Credit(s) __________ Total Amount Enclosed __________ ------------------------------------------------------------ Payment may be made by check or money order ------------------------------------------------------------ GAP Development Company 24242 Porto Fino RT 7715 Laguna Niguel, CA 92677-3844 INDEX ----- @ 33 BLUE 11 a.ccess% 22 BMAGENTA 11 ANSI 2, 3, 11, 17, 22, 33, 35 BRED 11 backspace 23 BROWN 11 bell 35 BWHITE 11 chat 2, 24, 29, 30, 36, 37, CYAN 11 38 GREEN 11 ckeypress% 23 MAGENTA 11 clear.scr 23 RED 11 COMMAND$ 5 WHITE 11 communications file 6 YELLOW 11 communications port 3, 5 General configuration file 5 NO 11 CTS 2 YES 11 CVDMBF 7, 16, 32 Integers CVSMBF 7, 16, 32 DOOR.SYS do.chat 24 alarm 12 do.pcb 6, 32, 39 baud 12 DOOR.SYS 5, 6, 12, 21, 30 bell 12 DTR 3 c.olor 12 elap.time 24 expert 12 Error 4, 5, 22, 27, 30 l.ocal 12 file number 5 level 12 Files minsleft 12 Aborting 34 node 12 Color 33 page 12 Communications 6 parity 12 Configuration 5, 28, 30 port 12 DOOR.SYS 31 printer 12 Errors 22 s.creen 12 GAPDOS.DAT 31, 38 userbaud 12 Include 4, 5 GAPDOS Opening 22 gapdos.baud 13 PCB USERS 32 gapdos.forumnum 13 PCBOARD.SYS 32 gapdos.givetime 13 Showing 33 gapdos.localc 13 System 24, 27 gapdos.minavail 13 USERS.DAT 32, 38 gapdos.port 13 Functions 22 gapdos.timecredit 14 GAPBBS.CNF 30 gapdos.userbaud 14 GAPDOS.DAT 9, 13, 21, 30 General get.string 13, 24, 25, 26, do.pcb 13 29, 36, 39 noup 13 get.time& 26 timecredit 13 getakey% 26 timeleft 13 getrand% 27 PCBSYS Global Variables pcbsys.minsleft 15 Constants pcbsys.timeallowed 15 ANSI pcbsys.timecredit 15 BBLACK 11 pcbsys.timegiven 15 BBLUE 11 pcbsys.timeon 15 BCYAN 11 pcbsys.timeused 15 BGREEN 11 pcbsys.ttlbytes 15 BLACK 11 pcbsys.userrec 15 Page 43 INDEX ----- PCBUSERS gapdos.exitdos 13 pcbuser.downloads 15 gapdos.userfirst 14 pcbuser.timeson 16 gapdos.userindex 14 pcbuser.uploads 16 gapdos.username 14 USERS General user.curdown 14 anystring1 13 user.lastfrm 14 bbs.dir 13 user.level 14 board.name 13 user.minutes 14 gendir 13 user.page 14 maindir 13 Longs sysname 13 DOOR.SYS PCBSYS downbytes 12 pcbsys.baud 15 downloads 12 pcbsys.calleralarm 15 maxbytes 12 pcbsys.colorc 15 recnum 12 pcbsys.ctime 15 timeson 12 pcbsys.display 15 upbytes 12 pcbsys.eactive 15 uploads 12 pcbsys.errcorrect 15 GAPDOS pcbsys.event 15 gapdos.callbytes 13 pcbsys.forumnum 15 gapdos.joined 13 pcbsys.node 15 gapdos.starttime 13 pcbsys.pagebell 15 General pcbsys.password 15 starttime 13 pcbsys.port 15 temptime 13 pcbsys.printer 15 timenow 13 pcbsys.sevent 15 USERS pcbsys.sysopnext 15 user.blts 14 pcbsys.userbaud 15 user.curbytes 14 pcbsys.userfirst 15 user.doors 14 pcbsys.username 15 user.downloads 14 PCBUSERS user.joined 14 pcbuser.bphone 15 user.lastmsg 14 pcbuser.city 15 user.mesleft 14 pcbuser.cnfregis 15 user.mesread 14 pcbuser.delete 15 user.timeson 14 pcbuser.downbytes 15 user.ttlbytes 14 pcbuser.expert 15 user.ttlmins 14 pcbuser.hphone 15 user.upbytes 14 pcbuser.lastconf 15 user.uploads 14 pcbuser.lastdate 16 Strings pcbuser.lastdir 16 DOOR.SYS pcbuser.lastime 16 bphone 12 pcbuser.lastmsg 16 city 12 pcbuser.lastmsg1 16 first 12 pcbuser.level 16 hphone 12 pcbuser.name 16 last 12 pcbuser.page 16 lastdate 12 pcbuser.passwd 16 password 12 pcbuser.protocol 16 subscrip 12 pcbuser.regisdate 16 username 12 pcbuser.upbytes 16 GAPDOS USERS gapdos.didnew 13 user.bphone 14 Page 44 INDEX ----- user.city 14 timeleft 26, 37 user.expert 14 Trimming Spaces 32 user.fname 14 update.clock 37 user.handle 14 USERS.DAT 9, 14, 21 user.hphone 14 user defined keys 4 user.lastdate 14 waitasec 37 user.lastdir 14 wrap.word 37 user.lasttime 14 write.gapdos% 38 user.lname 14 write.gapuser% 38 user.passwd 14 write.pcbsys% 39 user.private 14 write.pcbuser% 39 user.protocol 14 { 33 user.subscribe 14 user.sysop 14 IEEE 6, 7 init.door 5, 15, 27, 28, 30, 31, 32 leave 5, 27 mbf 6, 7 MKDMBF 39 MKSMBF 39 more 28 New Line 28, 35 nl 28 no.carrier 28 node 6 noup 25 ON KEY 4 open.gap% 28 pagesysop 29 pause 29, 37 PCB USERS 15, 21 PCBOARD.SYS 5, 6, 15, 21 putachar 29, 35 putkey 30, 35 read.cnf 4, 5, 30 read.doorsys% 31 read.gapdos% 31 read.gapuser% 32 read.pcbsys% 32 read.pcbuser% 32 right.trim$ 32 set.status 33 show.file 33 show.mess 23, 35, 39 Spaces Trimming 32 USERS.DAT 38 Status Line 2, 33, 34, 37 string output 35 Subroutines 22 time.credit 36 time.left 37 timecredit 36, 38 Page 45